feat(cli): configure MCP natively across coding agents - #187

Replace the subprocess installer in `setup mcp` with a built-in one that
detects installed agents, pre-selects them in a picker, and offers to install
rules telling those agents to prefer Firecrawl for web search and scraping.

Covers Claude Code, Cursor, VS Code, Codex, OpenCode, Windsurf, Zed, Hermes
Agent, and OpenClaw through per-agent flags, `--project` for project scope, and
`--rules` / `--no-rules` for scripted runs. `-y` stays MCP-only. The two
launchers were previously reachable only by flag, so a plain `setup mcp` never
offered them; they now sit in the picker alongside the editors, and because a
launcher shells out to a CLI, a missing binary is reported against that one
agent instead of ending the run.

Credential handling is unchanged in principle and stricter in reach: an API key
is never written as a literal. Knowing which agents were selected means each one
receives a reference to FIRECRAWL_API_KEY in the syntax it expands, so the setup
no longer has to refuse a run that omits --agent. Agents with no verified syntax
fall back to the keyless endpoint and say so rather than persisting a secret.

Config edits are surgical. JSON is patched through a JSONC-aware editor so
commented settings files parse at all and keep their comments, and TOML tables
are replaced along with any stale sub-tables left by a previous stdio entry.
Reruns are byte-identical.

Also gives every setup test a throwaway HOME and resets spawn mocks between
tests, since MCP setup now writes real config files and would otherwise rewrite
the developer's own agent settings; and teaches doctor about the `servers` and
`context_servers` keys so those registrations are recognized.

…keys

Project scope fought the one-command-every-agent goal, and --agent hermes/openclaw aborted on a stored key while the boolean flags wrote keyless config.

… artifacts

Three Firecrawl MCP configs were tracked at the repository root. Tests wrote
them into the working directory and a broad `git add` swept them in, so anyone
opening this checkout inherited MCP servers from the repo. Removed, and every
setup test now runs in its own working directory so project-relative writes
cannot reach the repository again.

A stored key behaved three different ways depending on how the target was
named: keyless for the boolean flags, keyless for `--agent hermes`, and a hard
abort for `--agent all`. The README documents keyless. `--agent all` now agrees
with the rest, and the launchers report through the same summary so the keyless
fallback is stated rather than implied by a bare installer log line.

`--agent launchers` was a synonym for every agent plus both launchers, which is
not what the name says. It now selects the launchers.

Launcher dispatch is exhaustive rather than treating anything that is not
Hermes as OpenClaw, and doctor recognises OpenCode's top-level `mcp` map, which
it previously reported as unregistered right after setup wrote it.

The scanner added in the previous commit closed a multi-line basic string at
the first `"""` it found, but a basic string honours backslash escapes, so
`\"""` is an escaped quote followed by two literal ones rather than the
terminator. Ending the string there marked the rest of it as ordinary config,
which is how a `[table]` written inside a string becomes a header the editor
will replace, taking the user's content with it.

Fence candidates are now skipped while the backslash run before them is odd.
An even run is a real terminator, since backslashes escape each other. Literal
strings are unaffected because they have no escapes at all.

Two defects in the new Hermes writer, both reported against the last commit:

* A server key with nothing under it, `mcp_servers:` on its own, parses as a
  null scalar. Setting a path through that refuses to descend, so setup failed
  on a valid config. The key has to be replaced with a collection node first;
  assigning a plain object raises the same error one level down, because the
  value is stored as-is rather than converted.
* Serialising the document tree drops a leading byte order mark and rewrites
  every line with LF. Both belong to the user's file, so they are captured from
  the input and restored on write, which is how the JSON and TOML writers
  already treat them.

OpenClaw was reported as having no rules mechanism. It has one: the workspace
AGENTS.md is a bootstrap file that OpenClaw injects into the system prompt on
every turn, treats as instruction context, and passes down to sub-agent
sessions. It is workspace-level rather than project-level, so it is reachable
from a global setup, and the rule now goes there fenced by markers like any
file the user also writes to.

The workspace can move, so the path follows OPENCLAW_WORKSPACE_DIR and the
profile suffix before falling back to ~/.openclaw/workspace. An explicit
agents.defaults.workspace in the config wins over both, but that file is JSON5
and out of reach here; landing the rule in an unused workspace is inert, unlike
a misplaced server entry.

The rule is only written when that AGENTS.md already exists. OpenClaw seeds the
file with its own instructions on first run, and creating it first would leave
the user with our section instead of those.

Writing a rule and registering the server are separate concerns, so a launcher
can take one without giving up its own MCP registration. Hermes still gets no
rule: it reads AGENTS.md from the working directory and deliberately ignores
one in $HOME, and its only global context file is SOUL.md, which is the user's
agent identity rather than a place for tool routing.

Setup could carry a key or run anonymously, but not sign in, so the one path
the docs present to a person at a terminal had no command behind it.
`--oauth` writes the sign-in endpoint instead of a credential, and each agent
starts the browser flow itself the first time it connects.

Sign-in is a different server URL rather than a different header, so it
replaces the credential rather than travelling beside it: an exported key is
ignored under --oauth and no Authorization header is written. The two are
separate endpoints, so combining --oauth with --keyless is rejected instead of
silently preferring one.

A URL alone is not enough for every agent. Hermes starts the flow only when the
entry carries `auth: oauth`, and OpenClaw ignores a static Authorization header
unless `auth: "oauth"` is set, which is also what gates its login command.
Those fields live beside the agent in the registry, next to the environment
syntax, and an agent without a verified sign-in shape gets no entry rather than
one that reports success and then exposes no tools.

No agent signs in during setup, and each one starts the flow differently, so
the summary prints the step per agent rather than one footer: `/mcp` in Claude
Code, `codex mcp login firecrawl`, Cursor Settings, and a browser on first use
for the rest.

Four defects reported against the sign-in commit, each confirmed against the
code before changing it:

* Replacing an empty `mcp_servers:` key dropped an inline comment sitting on
  it. The comment belongs to the null value being replaced; a block map has no
  inline slot on its key, so it now moves to the head of the section instead of
  disappearing with the node it was attached to. Preserved and relocated beats
  silently deleted.
* A marker-fenced rule section was written with LF regardless of the file it
  joined, so updating a CRLF AGENTS.md left mixed endings. The section now
  adopts the line endings of the file it is written into, which is how the
  JSON, TOML, and YAML writers already behave.
* The OpenClaw workspace was resolved from the environment and the documented
  defaults alone, so a workspace moved through config took the rule to a path
  the launcher never reads. OpenClaw is now asked where its workspace is, since
  its config is JSON5 and out of reach; the previous resolution stays as the
  fallback for when the CLI cannot answer.
* Declining rules reported OpenClaw as not supporting them, which stopped being
  true when it gained a rule. It reports skipped now, and unsupported is left
  for agents that genuinely have nowhere to put one.

setup mcp promises a global entry in a file we can parse, never a literal key,
plus an optional rule file we own. Claude Code, Cursor, VS Code, and Codex meet
that as registry data: the only difference is the file format. OpenCode is the
same kind of write with its own map key and header form, so it stays.

Hermes and OpenClaw were each a second product. Hermes needed a YAML writer, an
owner-only create mode, an extra entry field for sign-in, and had no global
rule file to own. OpenClaw needed a subprocess, a JSON5 config we cannot parse,
a workspace probe, a duplicate credential builder, and a rule that could only
be written if its AGENTS.md already existed. Neither shaped the product; both
shaped the code around them.

They stay supported and stop being written. `--hermes`, `--openclaw`, and their
names on --agent print the server URL and succeed, the way an agent we install
skills for but write no MCP config for already did. Skills and firecrawl launch
are untouched, and the URL still works for both.

Removing the two takes the whole launcher concept with them: the subprocess
runner and its Windows argv escaping, the second credential path, launcher
detection, the YAML writer, and the target/client split that existed only
because launchers were not clients. Five agents, one contract, one writer.

…ed yaml dep

Two defects reported against the scope change:

* The URL-only branch returns before the writers run, and the mutual-exclusion
  check lived with the writers, so `--hermes --oauth --keyless` printed a
  sign-in URL and exited zero while `--cursor --oauth --keyless` was rejected.
  The check now runs at the top of installMcp, ahead of everything that reports
  or returns.
* Removing the Hermes writer took the last import of the yaml package with it.
  Nothing under src/ imports it now, so it is dropped from the manifest and the
  lockfile rather than shipped unused.

A third finding, that a test leaks FIRECRAWL_API_KEY into later tests, does not
hold: beforeEach deletes that variable and afterEach restores the original, so
each test starts without it. The assignment is also load-bearing where it is,
since the assertion it supports is that sign-in drops a key that was present.

A rule tells an agent to prefer firecrawl_search and firecrawl_scrape. It was
written even when the server entry for that agent had failed, so an agent could
be instructed to reach for tools it had no way to call. The rule now depends on
the entry landing. The dependency runs one way only: a failed rule still leaves
a working MCP server, which is what keeps the two writes separate.

A run that configured some of the chosen agents also exited zero, so a script
could not tell a partial install from a complete one. The summary already named
what failed; the exit code now agrees with it. Quiet mode is unchanged, since it
runs inside init and launch, which report their own outcome and continue.

Also ignores .cursor/, alongside the editor directories already listed. Nothing
from it was ever tracked, but it is the same kind of workspace artifact a broad
`git add` swept into the repo once already.

Failing the run on a partial install swallowed the tail of `--agent all`: the
throw left before the Hermes and OpenClaw lines printed, and their URL is the
whole answer for those two, so the run that most needed to mention them was the
one that did not. The report now runs whether or not the writers threw.

The exit code is unchanged. Configuring what it can and then reporting failure
is the same contract as before, since per-agent isolation is about the other
agents still being configured, not about the command claiming success.

This reverts the scope reduction and everything built on it. The PR keeps the
harnesses main already supports and changes only how MCP gets installed:
Claude Code, Cursor, VS Code, Codex, OpenCode, Hermes Agent, and OpenClaw, with
native writers in place of the add-mcp subprocess.

Narrowing the set to the agents that share one contract is a real argument, but
it is a different change: it drops harnesses, so it has to move `firecrawl
launch` and the docs with it, and it should be judged on its own rather than
riding along with the writer swap. It comes back as "stop auto-configuring
Hermes and OpenClaw" if we want it.

So the Hermes YAML writer and the OpenClaw launcher are back, `launch`
configures both exactly as it does on main, and the URL-only path invented here
is gone rather than left as a second way an agent can be supported.

Kept from the reverted range, since none of it depends on the smaller set: the
auth-mode check ahead of every branch, rules not being written for an agent
whose server entry failed, a partial run failing the command, and .cursor/ in
.gitignore. The launcher isolation test now asserts both halves of that last
one: OpenClaw failing is reported, and Cursor beside it is still configured.

Those three branches passed `yes: true` into installMcpClients to skip the
picker, but naming the targets already does that: the picker only runs when no
targets were selected, and each of these arrives with a list. What `yes` still
reached was the rules prompt, so `--agent cursor` asked whether to install rules
and `--agent all` silently decided no.

Dropping the flag leaves the picker skipped as before and lets the question be
asked. Nothing else moves: without a TTY the run is still non-interactive, `-y`
still declines rules, and `--rules` still forces them.

The oauth report prefixed every step with "Sign in" and then repeated the
verb inside the step itself, so VS Code read "Sign in sign in from the MCP
view in VS Code". Checking each agent against its own docs showed the
duplication was hiding worse problems: VS Code has no MCP view and runs
client registration itself, Cursor surfaces a needs-login control of its
own, OpenCode prompts on first use, and Claude Code shows a startup notice
for any server that answers 401, which the sign-in endpoint does. Those
four now print nothing.

The three that do need a command keep one, and the strings are corrected:
Codex leads with its own command but names the Authenticate action, since
the desktop app and the IDE extension share the config file this writes and
only the CLI needs the command. Hermes reloads config on a 30s timer that
cannot outlast an interactive flow, so it names the login command and says
to run it from a new terminal rather than claiming the browser opens by
itself. The footer no longer promises that every agent prompts you.

The integrations checkbox named three editors, but MCP setup writes to every
agent it detects, so the list both undersold it and went stale as agents were
added. It now reads like the skills entry above it and names no agents.

printNextSteps also offered "Add MCP: firecrawl setup mcp" unconditionally,
including right below its own "✓ MCP server installed". stepIntegrations now
reports whether the install succeeded, and the line prints only for someone
who does not have it: skipping the integration or a failed install both keep
it.

Quiet mode fails only when nothing lands, so a run where one agent failed
resolved normally and init printed "✓ MCP server installed" directly under
its own ✗ line, then hid the "Add MCP" next step that would have fixed it.
installMcp now returns whether every targeted agent was configured, and init
claims success only on that; a partial run points at "firecrawl setup mcp"
and keeps the next step.

The OpenClaw workspace lookup also expanded any leading tilde against home,
so a `~other/ws` workspace, which names another account to a shell, wrote the
rule into $HOME/other/ws instead. Expansion is now limited to `~` and a `~/`
prefix, and reads the resolved home from the context the writers already
carry rather than calling os.homedir() again.

Hermes has no global rule file, so --rules was going silent: clients only
reach unsupported after rules were requested, and the dropped line hid that.